Skip to content

Secrets API: Small hardening and documentation follow-ups - #15989

Open
ericmann wants to merge 4 commits into
WordPress:trunkfrom
ericmann:secrets-hardening
Open

ericmann wants to merge 4 commits into
WordPress:trunkfrom
ericmann:secrets-hardening

Conversation

@ericmann

Copy link
Copy Markdown

Four small follow-ups to the Secrets API, one per commit so each can be taken or left on its own.

What changes

  1. A root key read that fails without a database error message is reported as a failed read. WP_Secrets_Key_Manager::read_stored_root_key() checked wpdb::$last_error, which is not set on every failure path. When the connection is not ready, wpdb::query() returns false and leaves it empty, so get_root_key( false ) reported "No root key is stored." Failure is now taken from the return value of wpdb::query(), as Secrets API: Report a failed read of a secret's record, or of the list, as an error #15974 does for a secret's record. The root key was never replaced in this case; only the error was wrong.
  2. Site Health no longer fails when a key cannot be generated. The key source test shows a newly generated WP_SECRETS_KEY line when no usable key is defined, and called random_bytes() without a try/catch. That test runs on every load of the Site Health screen and in the weekly scheduled check. It now catches the exception and asks for a base64-encoded random 32-byte value without showing one. This adds one string.
  3. Inline documentation.
    • The example for wp_is_secrets_api_available() wrote a secret without checking wp_secrets_provider_is_writable() or the result of wp_set_secret(). It now checks both, and says what to do with a provider that is available but not writable.
    • WP_Secrets_Key_Manager::get_keyring() referred to wp secret dropin and wp secret health, which are not part of core.
    • WP_Secrets_Cipher and WP_Secrets_Store said the record is assembled by the functions in secrets.php. WP_Secrets_Libsodium_Provider assembles it.
    • WP_Secrets_Keyring says where the conformance suite is.
    • Blank lines around three methods of WP_Secrets_Libsodium_Provider.
  4. Three more parameters are marked #[\SensitiveParameter]: WP_Secrets_Cipher::is_valid_master_key(), WP_Secrets_Config_Key_Provider::is_usable_key_value() and wp_secrets_memzero(). Follow-up to r65375 and r65466.

Not changed

Conflicts to expect

The first commit changes the two queries in read_stored_root_key(). #15976 and #15968 both change the network ID those queries use, so whichever lands second needs a small manual merge there. The other three commits don't touch those lines.

Testing

  • New test: test_a_root_key_read_that_fails_without_an_error_message_is_reported_and_not_replaced. With trunk's key manager it fails, because the read reports secret_key_unavailable.
  • --group secrets: 437 tests on single site and 445 on multisite, no failures (PHP 8.5).
  • --group site-health: 121 tests, no failures.
  • PHPCS is clean on the changed files.
  • The random_bytes() failure path has no test, because the function can't be made to throw from a test.

Trac ticket: https://core.trac.wordpress.org/ticket/66187

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Fable 5.2
Used for: Writing the changes, the test and this description.


This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

`WP_Secrets_Key_Manager::read_stored_root_key()` detected a failed read from `wpdb::$last_error`, which is not set on every failure path. When the connection is not ready, `wpdb::query()` returns false and leaves it empty, so the read reported that no root key is stored.

Failure is now taken from the return value of `wpdb::query()`, so that case reports `secret_store_unavailable`.

See #66187.
The key source test shows a newly generated `WP_SECRETS_KEY` line when no usable key is defined. It called `random_bytes()` without catching the exception it throws when no source of randomness is available. The test runs on every load of the Site Health screen and in the weekly scheduled check, so that exception was fatal for both.

The test now catches it, and asks for a base64-encoded random 32-byte value without showing one.

See #66187.
* The example for `wp_is_secrets_api_available()` wrote a secret without checking `wp_secrets_provider_is_writable()` or the result of `wp_set_secret()`. It now checks both, and says what to do with a provider that is available but not writable.
* `WP_Secrets_Key_Manager::get_keyring()` referred to WP-CLI commands that are not part of core.
* `WP_Secrets_Cipher` and `WP_Secrets_Store` said the record is assembled by the functions in `secrets.php`. `WP_Secrets_Libsodium_Provider` assembles it.
* `WP_Secrets_Keyring` now says where the conformance suite is.
* Fix the blank lines around three methods of `WP_Secrets_Libsodium_Provider`.

See #66187.
`WP_Secrets_Cipher::is_valid_master_key()`, `WP_Secrets_Config_Key_Provider::is_usable_key_value()` and `wp_secrets_memzero()` receive key material or a secret value, so their parameters are now marked with `#[\SensitiveParameter]` and are left out of stack traces.

Follow-up to r65375, r65466.

See #66187.
@github-actions

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props ericmann.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@github-actions

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant